Demo: migrate to SDK v2 by extending the Protocol base class#712
Draft
felixweinberger wants to merge 9 commits into
Draft
Demo: migrate to SDK v2 by extending the Protocol base class#712felixweinberger wants to merge 9 commits into
felixweinberger wants to merge 9 commits into
Conversation
Replaces the Client/Server subclassing from the v2 migration with direct Protocol extension, now that the SDK exports Protocol from the client package root. This restores the v1 wire contract on the iframe channel: ui/initialize is the first and only handshake, so deployed hosts keep working unchanged. Deleted with the double handshake: the inner MCP initialize round-trip and its pinned protocol version, the contentless inner capabilities and their retro-registration plumbing, the oninitialized defineProperty shadow, and the getCapabilities/getHostCapabilities split (v1 getCapabilities restored). Tests pin the wire order and assert no MCP initialize is sent in either direction. Note: package.json overrides point the SDK packages at locally built tarballs carrying the Protocol export; replace with published versions before any upstream PR.
The Protocol-based migration needs the Protocol class exported from the package roots, which lands in modelcontextprotocol/typescript-sdk#2501. Pin the preview builds so the branch is installable; swap to the next published beta once that PR is released.
@modelcontextprotocol/ext-apps
@modelcontextprotocol/server-basic-preact
@modelcontextprotocol/server-basic-react
@modelcontextprotocol/server-basic-solid
@modelcontextprotocol/server-basic-svelte
@modelcontextprotocol/server-basic-vanillajs
@modelcontextprotocol/server-basic-vue
@modelcontextprotocol/server-budget-allocator
@modelcontextprotocol/server-cohort-heatmap
@modelcontextprotocol/server-customer-segmentation
@modelcontextprotocol/server-debug
@modelcontextprotocol/server-lazy-auth
@modelcontextprotocol/server-map
@modelcontextprotocol/server-pdf
@modelcontextprotocol/server-scenario-modeler
@modelcontextprotocol/server-shadertoy
@modelcontextprotocol/server-sheet-music
@modelcontextprotocol/server-system-monitor
@modelcontextprotocol/server-threejs
@modelcontextprotocol/server-transcript
@modelcontextprotocol/server-video-resource
@modelcontextprotocol/server-wiki-explorer
commit: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Demonstration of the
Protocol-based v2 migration discussed in #710 — built directly on top of #710's commits (thanks @khandrew1, the package/schema/zod migration there carries this branch). Draft: depends on modelcontextprotocol/typescript-sdk#2501, pinned here via its pkg.pr.new preview builds.Motivation and Context
#710 subclasses the v2
Client/Serverroles, which puts a core MCPinitializehandshake on the iframe channel beforeui/initialize. Deployed hosts don't recognize a view-initiatedinitializeand reject it, so new views would break existing hosts.typescript-sdk#2501 exports the
Protocolbase class from the client/server package roots.Protocol.connect()performs no handshake, soAppandAppBridgecan extend it directly — same shape as v1 — and the wire contract stays exactly v1:ui/initializeis the first and only handshake. Existing hosts keep working unchanged.Compared to #710's head this removes the inner-handshake machinery entirely (−61 lines): the pinned inner protocol version, the contentless inner capabilities and their retro-registration, the
oninitializedproperty shadowing, and thegetCapabilities/getHostCapabilitiessplit (v1getCapabilitiesrestored).One behavior note: host-side
tools/callresult validation from the baseServeris gone — as in v1, results are validated on the App side (CallToolResultSchema), so malformed host results surface as parse errors in the view.How Has This Been Tested?
["ui/initialize", "ui/notifications/initialized"]and assert noinitialize/notifications/initializedis sent in either direction.tools/callall work with onlyui/*methods on the wire.app-with-deps.js): 337 KB on v1 → 422 KB here → 482 KB on Migrate ext-apps to @modelcontextprotocol/server v2 SDK #710's head.Breaking Changes
None relative to v1 wire behavior — that's the point. Relative to #710 (unreleased):
AppBridge.getHostCapabilities()is folded back intogetCapabilities(), and the inner MCP handshake no longer happens.Types of changes
Checklist
Additional context
The SDK packages are pinned to the pkg.pr.new preview builds of typescript-sdk#2501, so
npm iworks on a checkout — but the lockfile-hygiene CI check (registry.npmjs.org-onlyresolvedURLs) is expected to fail until that PR ships in a published beta. Once it does, the three specs inpackage.json(devDependencies + overrides) become exact registry versions and CI should go green. Happy for this to be folded into #710 rather than land separately.